filter

Type

command

Summary

Filters each line, item, key or element in a source container or expression, removing the lines, items, keys or elements that do or don't match a pattern.

Syntax

filter [{lines | items | keys | elements} of] <filterSource> {with| without | [not] matching} [wildcard] [pattern] <wildcardPattern> [into <targetContainer>]

filter [{lines | items | keys | elements} of] <filterSource> {with| without | [not] matching} regex [pattern] <regexPattern> [into <targetContainer>]

filter [{lines | items | keys | elements} of] <filterSource> where <whereExpression> [into <targetContainer>]

Description

Use the filter command to pick specific lines, items, keys or elements in a container or expression.

The filter...with form and the filter...matching form retain the lines, items, keys or elements that contain a match for the specified wildcard pattern or regex pattern.

The filter...without form and the filter...not matching form discard the lines, items, keys or elements that do not contain a match for the specified wildcard pattern or regex pattern.

If you don't specify lines, items, keys or elements then lines are filtered by default.

*Note

• If neither wildcard pattern or regex pattern forms are explicitly specified then the wildcard pattern form is assumed.

If no targetContainer is specified, and you filter a container, the container contents will be replaced by the filtered result.

When using the where form of the filter command the each keyword may be used in the whereExpression for the value to be filtered.

Parameters

Name	Type	Description
filterSource		An expression that evaluates to a string, array, or a container. wildcard pattern: An expression which evaluates to a string in the form of a wildcard pattern. regex pattern: An expression which evaluates to a string in the form of a regex pattern.
targetContainer		An expression that evaluates to a container.
whereExpression		An expression that evaluates to a boolean.

Examples

local tVar
put the propertyNames into tVar
filter tVar with "[az]*"
-- tVar contains all property names beginning with a or z

-- Filtering a string literal causes the filtered string to be placed in the it variable
filter items of "apple,banana,cherry" with regex pattern "b.*"
-- it contains "banana"

local tSource, tBackscriptObjects
put the backscripts into tSource
filter lines of tSource without regex pattern "^stack.*" into tBackscriptObjects
-- tBackscriptObjects contains a list of non-stack backscripts

create field "Numbers"
put "123,234,345,456,567,678,789" into field "Numbers"
filter items of field "Numbers" matching "*[!35-9]"
-- field contains "234"

local tArray
put true into tArray["foo"]
put false into tArray["bar"]
filter keys of tArray with "f*"
put the keys of tArray is "foo"

local tArray
put true into tArray["foo"]
put false into tArray["bar"]
filter elements of tArray without "f*"
put the keys of tArray is "foo"

create field "Numbers"
put "123,234,345,456,567,678,789" into field "Numbers"
filter items of field "Numbers" where each >= 300 and each <= 500
-- field contains "345,456,567"

command FilterIt pValue
   filter lines of pValue where checkLine(each)
end FilterIt

function checkLine pLine
   return item 1 of pLine > item 2 of pLine
end checkLine

Related

property: caseSensitive

command: replace, sort

function: matchChunk, matchText, replaceText

glossary: container, expression, wildcard pattern, regex pattern

keyword: it, each

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile